<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>rest_client_c: REST C API Documentation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">rest_client_c
   &#160;<span id="projectnumber">1.0</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('index.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">REST C API Documentation </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="intro_sec"></a>
Introduction</h1>
<p>This API provides a comprehensive, easy to use interface into REST APIs. </p>
<h1><a class="anchor" id="objects"></a>
Using the Objects</h1>
<p>The APIs utilize an <a class="el" href="structObject.html" title="The base Object class structure contains the textual name of the class; useful for debugging...">Object</a> pattern in C. The pattern can be used in one of two ways:</p>
<ul>
<li>Stack-based objects<ol type="1">
<li>Declare an object in your local variables</li>
<li>Intialize it by calling the &lt;Class&gt;_init function, passing the object address as 'self'</li>
<li>Call member functions using the object address as 'self'</li>
<li>Destroy the object by calling the &lt;Class&gt;_destroy function, passing the object address as 'self'.</li>
</ol>
</li>
<li>Heap-based objects<ol type="1">
<li>Declare an object pointer in your local variables.</li>
<li>Intialize the object by calling the &lt;Class&gt;_init function, using malloc(sizeof(&lt;Class&gt;)) as the input 'self' parameter. Assign the output to your pointer.</li>
<li>Call member functions by using the pointer as 'self'.</li>
<li>Destroy the object by calling the &lt;Class&gt;_destroy function, passing the pointer as 'self'.</li>
<li>Free the pointer with free().</li>
</ol>
</li>
</ul>
<h3>Examples</h3>
<h4>Stack-based <a class="el" href="structObject.html" title="The base Object class structure contains the textual name of the class; useful for debugging...">Object</a></h4>
<div class="fragment"><div class="line">       <span class="keywordtype">void</span> main(<span class="keywordtype">void</span>) {</div>
<div class="line">           <a class="code" href="structObject.html" title="The base Object class structure contains the textual name of the class; useful for debugging...">Object</a> myobj;</div>
<div class="line">  </div>
<div class="line">           <a class="code" href="group__Object__API_gab5fcda6f3216735c1815d5ca2deb7bc4.html#gab5fcda6f3216735c1815d5ca2deb7bc4" title="Initializes a new object.">Object_init</a>(&amp;myobj);</div>
<div class="line">           printf(<span class="stringliteral">&quot;Object class: %s\n&quot;</span>, <a class="code" href="group__Object__API_ga0d17c18f03bfa2a3424924844261b9c3.html#ga0d17c18f03bfa2a3424924844261b9c3" title="Gets the name of the object&#39;s class.">Object_get_class_name</a>(&amp;myobj));</div>
<div class="line">           <a class="code" href="group__Object__API_ga800f6abaff124d512ef54400a7fd57fb.html#ga800f6abaff124d512ef54400a7fd57fb" title="Destroys a object.">Object_destroy</a>(&amp;myobj);</div>
<div class="line">       }</div>
</div><!-- fragment --><h4>Heap-based <a class="el" href="structObject.html" title="The base Object class structure contains the textual name of the class; useful for debugging...">Object</a></h4>
<div class="fragment"><div class="line">       <span class="keywordtype">void</span> main(<span class="keywordtype">void</span>) {</div>
<div class="line">           <a class="code" href="structObject.html" title="The base Object class structure contains the textual name of the class; useful for debugging...">Object</a> *myobj;</div>
<div class="line">  </div>
<div class="line">           myobj = <a class="code" href="group__Object__API_gab5fcda6f3216735c1815d5ca2deb7bc4.html#gab5fcda6f3216735c1815d5ca2deb7bc4" title="Initializes a new object.">Object_init</a>(malloc(<span class="keyword">sizeof</span>(<a class="code" href="structObject.html" title="The base Object class structure contains the textual name of the class; useful for debugging...">Object</a>)));</div>
<div class="line">           printf(<span class="stringliteral">&quot;Object class: %s\n&quot;</span>, <a class="code" href="group__Object__API_ga0d17c18f03bfa2a3424924844261b9c3.html#ga0d17c18f03bfa2a3424924844261b9c3" title="Gets the name of the object&#39;s class.">Object_get_class_name</a>(myobj));</div>
<div class="line">           <a class="code" href="group__Object__API_ga800f6abaff124d512ef54400a7fd57fb.html#ga800f6abaff124d512ef54400a7fd57fb" title="Destroys a object.">Object_destroy</a>(myobj);</div>
<div class="line">           free(myobj);</div>
<div class="line">       }</div>
</div><!-- fragment --><h1><a class="anchor" id="making"></a>
REST calls</h1>
<p>Making a REST call invovles two steps. First, you initialize a <a class="el" href="structRestClient.html" title="Configuration for a RestClient.">RestClient</a> object to maintain connection state between you and the server. After creating the <a class="el" href="structRestClient.html" title="Configuration for a RestClient.">RestClient</a>, you create one or more <a class="el" href="structRestRequest.html" title="Defines the RestRequest object.">RestRequest</a> and <a class="el" href="structRestResponse.html" title="This is a standard response from REST operations.">RestResponse</a> objects to send and receive data from the REST service.</p>
<h1><a class="anchor" id="Customization"></a>
Customization</h1>
<p>There are two points for customizing how the requests are executed. First, you can add a rest_curl_config_handler function to the <a class="el" href="structRestClient.html" title="Configuration for a RestClient.">RestClient</a> object. This function will be executed just before each request is sent and will allow you to inspect and/or tweak the settings on the CURL handle. Examples of this would be to enable/disable logging (<a class="el" href="group__REST__API_gab355d76d638f2ea2b09299d0b70436e9.html#gab355d76d638f2ea2b09299d0b70436e9" title="This is a CURL configuration function that enables verbose logging of the request and response via CU...">rest_verbose_config()</a>), disable SSL certificate checking (<a class="el" href="group__REST__API_ga71b3e85801bc1a75c6a9edd867d2cd24.html#ga71b3e85801bc1a75c6a9edd867d2cd24" title="This is a CURL configuration function that will disable SSL certificate validation, including host validation.">rest_disable_ssl_cert_check()</a>), etc.</p>
<p>The second customization point is with RestFilter objects. Each <a class="el" href="structRestRequest.html" title="Defines the RestRequest object.">RestRequest</a> is executed with a RestFilter chain. This chain allows you to control the request flow, modify the request, parse the response, etc. Some examples are authentication management, request signing, XML parsing, error handling, etc. Note that every request must be executed with a handler that actually invokes CURL to send the request. The default implementation is <a class="el" href="group__REST__API_ga541a53a9ff5697d4fff8accdc999f957.html#ga541a53a9ff5697d4fff8accdc999f957" title="This is usually the last filter in the chain and executes the HTTP request using cURL.">RestFilter_execute_curl_request()</a>.</p>
<h1><a class="anchor" id="Extension"></a>
Extension</h1>
<p>While you can use the default implementations of <a class="el" href="structRestRequest.html" title="Defines the RestRequest object.">RestRequest</a> and <a class="el" href="structRestResponse.html" title="This is a standard response from REST operations.">RestResponse</a> to execute generic REST requests, you will likely want to subclass these classes to provide enhanced functionality. For example, if a server sends back a JSON response, you could have a JSON response parser implementation that parses the response and sets fields in a custom <a class="el" href="structRestResponse.html" title="This is a standard response from REST operations.">RestResponse</a> class.</p>
<h1><a class="anchor" id="Example"></a>
Example</h1>
<p>A basic request to load the content of <a href="http://www.google.com">http://www.google.com</a> would look like this:</p>
<div class="fragment"><div class="line">    <a class="code" href="structRestClient.html" title="Configuration for a RestClient.">RestClient</a> c;</div>
<div class="line">    <a class="code" href="structRestRequest.html" title="Defines the RestRequest object.">RestRequest</a> req;</div>
<div class="line">    <a class="code" href="structRestResponse.html" title="This is a standard response from REST operations.">RestResponse</a> res;</div>
<div class="line">    <a class="code" href="structRestFilterTag.html" title="A linked list of filter functions to apply to the request.">RestFilter</a>* chain = NULL;</div>
<div class="line">  </div>
<div class="line">    <span class="comment">// Initialize the RestClient</span></div>
<div class="line">    <a class="code" href="group__REST__API_ga0154e04e8109a08aa4a8773199b84648.html#ga0154e04e8109a08aa4a8773199b84648" title="Initializes a RestClient object.">RestClient_init</a>(&amp;c, <span class="stringliteral">&quot;www.google.com&quot;</span>, 80);</div>
<div class="line">  </div>
<div class="line">    <span class="comment">// Intialize the request and response objects</span></div>
<div class="line">    <a class="code" href="group__REST__API_ga4ed741041689f0ba0af5aa9ae2425b90.html#ga4ed741041689f0ba0af5aa9ae2425b90" title="Initializes a new RestRequest object.">RestRequest_init</a>(&amp;req, <span class="stringliteral">&quot;/&quot;</span>, GET);</div>
<div class="line">    <a class="code" href="group__REST__API_ga7729c76a3f1f4ea7dbe68f5e6fb804eb.html#ga7729c76a3f1f4ea7dbe68f5e6fb804eb" title="Initializes a RestResponse object.">RestResponse_init</a>(&amp;res);</div>
<div class="line">  </div>
<div class="line">    <span class="comment">// Build a filter chain to execute the request</span></div>
<div class="line">    chain = <a class="code" href="group__REST__API_gad2a350560fed1b14418e77831717237f.html#gad2a350560fed1b14418e77831717237f" title="Adds a filter to the head of the filter chain.">RestFilter_add</a>(chain, &amp;<a class="code" href="group__REST__API_ga541a53a9ff5697d4fff8accdc999f957.html#ga541a53a9ff5697d4fff8accdc999f957" title="This is usually the last filter in the chain and executes the HTTP request using cURL.">RestFilter_execute_curl_request</a>);</div>
<div class="line">  </div>
<div class="line">    <span class="comment">// Execute the request</span></div>
<div class="line">    <a class="code" href="group__REST__API_gad0944d101867fb49ed2623f5d7a6cc4a.html#gad0944d101867fb49ed2623f5d7a6cc4a" title="Executes a REST request.">RestClient_execute_request</a>(&amp;c, chain, &amp;req, &amp;res);</div>
<div class="line">  </div>
<div class="line">    <span class="comment">// Check result.  If there is an issue communicating with the server (DNS</span></div>
<div class="line">    <span class="comment">// failures, connection failures, etc), the error will be in curl_error.</span></div>
<div class="line">    <span class="comment">// If the connection succeeds, the HTTP response code will be in http_code.</span></div>
<div class="line">    assert_int_equal(0, res.<a class="code" href="group__REST__API_ga130c895035dbbf0b5c2078850ddc6b79.html#ga130c895035dbbf0b5c2078850ddc6b79" title="Error code from libcurl.">curl_error</a>);</div>
<div class="line">    assert_int_equal(200, res.<a class="code" href="group__REST__API_ga85a61f90362e9f93e702cad1032d468f.html#ga85a61f90362e9f93e702cad1032d468f" title="HTTP code of the last operation.">http_code</a>);</div>
<div class="line">  </div>
<div class="line">    <span class="comment">// Cleanup</span></div>
<div class="line">    <a class="code" href="group__REST__API_ga9a142aee13d749dbadc1bb35bccff4ce.html#ga9a142aee13d749dbadc1bb35bccff4ce" title="Frees a filter chain.">RestFilter_free</a>(chain);</div>
<div class="line">    <a class="code" href="group__REST__API_ga29c2764d71d33ab560b68d6568862140.html#ga29c2764d71d33ab560b68d6568862140" title="Destroys a RestResponse object.">RestResponse_destroy</a>(&amp;res);</div>
<div class="line">    <a class="code" href="group__REST__API_ga1643c4796e06226308ad1d8c19e4f116.html#ga1643c4796e06226308ad1d8c19e4f116" title="Destroys a RestRequest.">RestRequest_destroy</a>(&amp;req);</div>
<div class="line">    <a class="code" href="group__REST__API_gac68772582c195829e34a4872a5d0343f.html#gac68772582c195829e34a4872a5d0343f" title="Destroys a RestClient object and its shared-state information.">RestClient_destroy</a>(&amp;c);</div>
</div><!-- fragment --> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Fri Oct 19 2012 13:02:48 for rest_client_c by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.1.1 </li>
  </ul>
</div>
</body>
</html>
